PC Media 2/PC MEDIA CD02.iso/share/prog/pb_menu/menulib.txt

Text File | 1993-06-10 | 19.1 KB | 573 lines

Menulib for Menusys
Add-On Library Routines
for Power BASIC 3.0
Version 1.0A

(C) Copyright 1993 by Tim Gerchmez
----------------------------------


            ** SUB/Function Reference **


Note: Especially powerful/high-level routines
      are marked with "*P*" to distinguish
      them from the rest.

Total Routines: 41
------------------------------------------------------------------------------
* SUB about

Displays the title and author of the current program
in a window and waits for the user to press ENTER or
click "OK" with the mouse.  Source code version is
required to modify this routine.

Example: CALL about

-----------------------------------------------------------------------------
* SUB alertbox (msg$)

Prints a one-line alert message on the screen and
waits for user to select OK with mouse or ENTER.

Example: CALL alertbox("File Not Found")

-----------------------------------------------------------------------------
* SUB background (ch%)

Fills the screen with a special character, creating a
background.  Uses colors in global variables clr% and bckg%.
Set ch% = 0 for black background, 1 for dark background, 2 for medium,
3 for light, 4 for pure.

Example: CALL background(2)

-----------------------------------------------------------------------------
* SUB bigprint (ch$, u$)

Prints a giant representation of the ASCII value in ch$.
Uses the character in u$ to represent the "dots" for the big
character.  Cursor Position is restored afterward.

Example: CALL bigprint ("A",chr$(219))

------------------------------------------------------------------------------
* SUB bigprintline (ln$, u$)

*P*

Print an entire line of characters in ln$ in giant size print.
Uses the character in u$ to print the giant "pixels."
Maximum: 10 characters in ln$ (80-col. screen).
Ready to print another line after routine is called .. begins
on the line the cursor is currently on.  Add 8 to the current
Y position for the next "screen line".  One screen will hold
about 3 lines of 10 giant characters.

Example:  LOCATE 1, 1
      CALL bigprintline("Testing123",chr$(219))

-----------------------------------------------------------------------------
* SUB checkbox (title$, optn$(), optn%())

Lets the user pick from a list of options with the mouse cursor or
the keyboard.  More than one option can be selected.  Set title$
to the title to display on the list, and DIM optn$() to the text
for the list of options.  Upon return, optn%(x) will contain either
a zero (user didn't select it) or a one (user selected it).  Subsequent
calls to checkbox will retain the user's choices in optn% if the array
isn't erased or redimensioned.

Example: title$="Select Options:":REDIM optn$(1:3), optn%(1:3)
     optn$(1)="Option 1":optn$(2)="Option 2":optn$(3)="Option 3"
     CALL checkbox(title$, optn$(), optn%())

-----------------------------------------------------------------------------
* SUB choosebox (msg$(), choice%)

Prints a multi-line message on the screen in a box,
and waits for user to select OK or CANCEL.
Returns 0 (OK) or 1 (Cancel)
Shortest string in msg$(x) should be >20.
Returns with user's choice in choice%:

0 = OK
1 = Cancel

Example: DIM msg$(1:2)
     msg$(1)="Would you like to"
     msg$(2)="Continue the current operation?"
     CALL choosebox(msg$(), choice%)
     IF choice% = 1 then print "Nope!" : end

-----------------------------------------------------------------------------
* SUB choosedir (d$, ch$)

*P*

Lets a user select from a directory entry on the screen.  Includes
ability to switch to new drives/subdirectories.  Call with d$ =
directory mask (normally "*.*").  Routine returns with user's choice
of filename in ch$ (or null string if cancelled).

Example: CALL choosedir("*.*",ch$)

-----------------------------------------------------------------------------
* SUB clearline (ln%)

Clears a selected screenline, including position 80, without
scrolling the screen.  Also preserves the current cursor position
and turns off the mouse cursor if necessary.

Example: CALL clearline (25)

-----------------------------------------------------------------------------
* FUNCTION endofline% (ln%)

Finds the position of the END OF TEXT on a specified screen line.
For example, if line 20 of the screen had the line


This is a test

          ^
          15

on it, PRINT endofline%(20) would return 15 (the last character
plus one, indicating the blank space following the line of text).
If there is no text on the specified screen line, a value of 80
will be returned.

Example: a% = endofline%(2)

-----------------------------------------------------------------------------
* SUB getdisk (d%)

Returns drive code of current or default drive.
0 = A, 1 = B, 2 = C, Etc. in d%.

Example: CALL getdisk(d%)

-----------------------------------------------------------------------------
* SUB getfontinfo (code%, points%, rows%, sg&, offset&)

EGA, MCGA, VGA
Returns a pointer to a font's character definition table, and
the points (bytes per character) and rows for that font.
Call with code% set to one of the following values:
0 = INT 1fh contents, 1 = INT 43h contents, 2 = ROM 8x14
font, 3 = ROM 8x8 font (chars 00h-7fh), 4 = ROM 8x8
font (chars 80h-ffh), 5 = ROM alternate 9x14 font, 6 =
ROM 8x16 font, 7 = ROM alternate 9x16 font.  Returns
points%, rows%(char. rows on screen - 1), sg% (segment of
char def table), offset% (offset of char. def table).
Used internally by BIGPRINT and BIGPRINTLINE to define
the shape of their giant character representations.

Example: CALL getfontinfo(3, points%, rows%, sg&, offset&)

-----------------------------------------------------------------------------
* SUB getpath (dv%, pth$)

Gets the current path from the root directory to the
current directory for the drive specified in dv%
(0 = Default, 1 = A, Etc).
Returns path in pth$ (including leading backslash).
If error, pth$ will = "".
Example: if current path was C:\PB\SLAM\, pth$
would return \PB\SLAM\.  If path was C:\ then
pth$ would return \.

Used internally by choosedir.

Example: CALL getpath(0, pth$)
     print "Current Path: "; pth$

-----------------------------------------------------------------------------
* SUB hscrollbar (starty%, startx%, length%)

Displays a horizontal "scroll bar" on the screen starting at position
starty%/startx%m, of length% characters.  See the demo program for an
example of hscrollbar.  This routine displays the scrollbar only - does
not control scrolling or anything else.  You will have to write the
routines yourself to display the scroll indicator, or wait for a future
version of menulib <grin>.

Example: CALL hscrollbar (23, 1, 20)

-----------------------------------------------------------------------------
* SUB infobox (msg$())

Prints a multi-line message on the screen in a box,
and waits for user to select OK with mouse or ENTER.
This differs from alertbox in that you can display
more than one line of text in the box.

Example: DIM msg$(2)
     msg$(1) = "Disk Problem -"
     msg$(2) = "Select OK"
     call infobox(msg$())

-----------------------------------------------------------------------------
* SUB inpbox (msg$, ip$, mx%, ll%, ul%)

*P*

Allows user input in a shadowed screen box.

Set msg$ to message, mx% to max length of user input,
ll% = lowest ASCII value permitted for input,
ul% = highest ASCII value permitted for input.

The string the user enters is returned in ip$.

For example, to input a 3-digit number:

msg$="Enter Number:"
mx% = 3
ll% = 48  :' ASCII value of "0"
ul% = 57  :' ASCII value of "9"
CALL inpbox(msg$, ip$, mx%, ll%, ul%)
number% = val(ip$)
print "You Entered ";ip%

-----------------------------------------------------------------------------
* SUB menupick (title$, mb$(), help$(), choice%)

Allows user to choose from a menu using either
the mouse or the cursor keys.  This is the typical
"vertical" menu displayed in the center of the screen,
with a highlighted bar than can be moved with the
mouse or crsr keys.  Screen is saved upon calling
and automatically restored when done.

title$ = title to display on menu
mb$() = text for menu choices
help$() = one-line help message for each menu option
choice% = choice returned by the user (0 if cancelled).

Set the cursor position (using LOCATE) to where you want
the upper left corner of the menu before calling this
routine.  help$() must be dimensioned to the same value
as mb$(), but need not be defined.  For ONE helpline for
all menu selections, set help$(1) to the text desired.

Example: title$="Select an Option"
     redim mb$(2),help$(2)
     mb$(1)="Option 1":mb$(2)="Option 2"
     help$(1)="Select an option or press ESC to cancel"
     CALL menupick(title$, mb$(), help$(), choice%)
     print "You Picked ";choice%

-----------------------------------------------------------------------------
* SUB messagebox (title$, msg$())

This routine prints a multi-line message in a box and exits
without delay.  Use for messages you want to remain on the
screen.  Title$ is printed at the top of the box, followed by
a horizontal line, followed by the text in msg$().  Upon exit,
the cursor is located at the position corresponding to the upper
left corner of the box.  You can use this to calculate where to
print further messages inside the box.

Example: LOCATE 10, 10
     redim msg$(1:1)
     title$="Loading..."
     msg$(1)="Record #:"
     call messagebox(title$, msg$())
     LOCATE csrlin+3, pos(0)+11
     print "5";  'Print Record #

-----------------------------------------------------------------------------
* SUB mgetpos

Checks current position of mouse cursor and updates the
corresponding global variables msy% and msx%.

Example: CALL mgetpos
     PRINT msy%; msx%

-----------------------------------------------------------------------------
* SUB mgetpress (button%, numpresses&, ycc%, xcc%)

Checks button indicated in button% (1 = left, 2 = right)
and returns status of buttons in globals lb% and rb%, number
of presses of specified button since last call (in numpresses&),
and Y and X coordinates of mouse cursor the last time the specified
button was pressed (in ycc% and xcc%).

Example: CALL mgetpress(button%, numpresses&, ycc%, xcc%)

-----------------------------------------------------------------------------
* SUB mgetrelease (button%, numreleases&, ycc%, xcc%)

Checks button indicated in button% (1 = left, 2 = right)
and returns status of buttons in globals lb% and rb%, number
of releases of specified button since last call (in numreleases&),
and Y and X coordinates of mouse cursor the last time the specified
button was released (in ycc% and xcc%).

Example: CALL mgetrelease(1, numreleases&, ycc%, xcc%)

-----------------------------------------------------------------------------
* SUB mousepick (ypos%(), xmin%(), xmax%(), pick%)

Checks arrays to see if mouse cursor is at positions specified
in: ypos%(x) = line, xmin%(x) = minimum x pos. on line ypos%(x)
and xmax%(x) = maximum x pos. on line ypos%(x).  If mouse cursor is
at any of these locations (inclusive) AND left button is pressed,
hilights desired area, waits til left button released, then returns
with position number in pick%.

This routine requires quite a bit of setting up to use effectively,
but essentially simulates a number of "buttons" on the screen that
can be "pressed" with the mouse.  This routine does not utilize the
keyboard at all, just the mouse, and you must draw the "buttons" on
the screen first before calling the routine.  DIM the arrays to the
number of "buttons" desired, Specify the Y position of each "button"
in ypos%(), the minimum (lowest) X position of each "button" in
xmin%(), and the maximum (highest) X position of each button in
xmax%().

Example: DIM ypos%(1:5), xmin%(1:5), xmax%(1:5): '5 "buttons"
     ... draw 5 "buttons" on the screen
     ... (set ypos%(1) thru ypos%(5), same with xmin%()
          and xmax%()
     CALL mousepick(ypos%(), xmin%(), xmax%(), pick%)
     'Check to see if any of the "buttons" were pressed,
      if so, return the button number in pick%.

-----------------------------------------------------------------------------
* SUB msetpos

Uses global variables msy% and msx% to set a new
position for the mouse cursor.  Change msy% and/or
msx% before calling this routine.

Example: msy% = 1: msx% = 1: CALL msetpos

-----------------------------------------------------------------------------
* SUB mwaitpress

Waits for a Mouse Button to be Pressed.

Example: CALL mwaitpress

-----------------------------------------------------------------------------
* SUB mybounds (mn%, mx%)

Sets minimum and maximum y-axis boundaries for mouse cursor
movement.

Example: CALL mybounds(2, 24)

-----------------------------------------------------------------------------
* FUNCTION pathstring$

Returns current disk/path in a string of the
form C:\QB\EXE\ ... Trailing backslash included.

Example: PRINT pathstring$

-----------------------------------------------------------------------------
* SUB picklist (lst$(), choice%)

*P*

Lets the user pick from a long list of options in a window, sizing
and scrolling the window as necessary.  Set lst$() to the text for
the list.  User's choice is returned in choice% (0 if cancelled).

Example: DIM lst$(100)
     ... Read in text file to lst$(x)
     CALL picklist(lst$(), choice%)
     PRINT "You Picked ";choice%

-----------------------------------------------------------------------------
* SUB printborder

Prints a border around the text screen

Example: CALL printborder

See demo program.

-----------------------------------------------------------------------------
* SUB printtitle (title$, starty%, hilight%)

Prints a title on the screen, either highlighted
or not highlighted.  See the demo program (title
is printed one line below the menu bar at the top).

Example: CALL printtitle("Program.dat", 20, 1)

-----------------------------------------------------------------------------
* SUB radiobox (title$, optn$(), choice%)

Displays a "radio button box" and lets user select one
option from a list of options.  Set title$ to title of
radio button box, optn$() to the options.  User's choice
is returned in choice%.  Use instead of checkbox if only
one option is possible out of a list of many.
If cancelled (with ESC), choice% = 0.

Example: DIM optn$(3)
     optn$(1) = "Option 1"....
     CALL radiobox("Pick One",optn$(), choice%)
     PRINT "You Chose ";choice%

-----------------------------------------------------------------------------
* SUB screenedit (x1%, x2%, y1%, y2%, ky$)

*P*

An advanced routine that allows a user to edit a portion of the
screen, using all the normal cursor keys and editing controls.
This is one routine that's made to be edited and modified, so
be sure to register and get the source code version of MENULIB.

x1%, x2% = Minimum and Maximum X Positions allowed (1-80).
y1%, y2% = Minimum and Maximum Y Positions allowed (1-25).
ky$ = keypress returned (if ESC or a scancode key is
      pressed that the routine doesn't recognize).

Example: CALL screenedit(1, 80, 1, 25, ky$)

-----------------------------------------------------------------------------
* SUB scrolldown (y1%, x1%, y2%, x2%, atrb%, ln%)

Scrolls a specified window of the screen down.
y1%,x1% = Upper Left Corner
y2%,x2% = Lower Right Corner
atrb% = Attrib stored in blanked area
ln% = Number of lines to scroll
Note: x/y pos start from 0 instead of 1

This routine is a duplicate of mscrolldown in MENUSYS, with
the parameters changed around a bit.  Use whichever you
prefer.

Example: CALL scrolldown(1, 1, 25, 80, 7, 1)

-----------------------------------------------------------------------------
* SUB scrollup (y1%, x1%, y2%, x2%, atrb%, ln%)

Scrolls a specified window of the screen up.
y1%,x1% = Upper Left Corner
y2%,x2% = Lower Right Corner
atrb% = Attrib stored in blanked area
ln% = Number of lines to scroll
Note: x/y pos start from 0 instead of 1

This routine is a duplicate of mscrollup in MENUSYS, with
the parameters changed around a bit.  Use whichever you
prefer.

Example: CALL scrollup(1, 1, 25, 80, 7, 1)

-----------------------------------------------------------------------------
* SUB selectback(ch%)

*P*

Allows a user to select a background color from a menu, and
returns selection in cl% ... -1 if user cancelled.

Example: CALL selectback(ch%)

-----------------------------------------------------------------------------
* SUB selectfore (cl%)

*P*

Allows a user to select a foreground color from a menu, and
returns selection in cl% ... -1 if user cancelled.

Example: CALL selectfore(cl%)

-----------------------------------------------------------------------------
* SUB setdisk (d%)

Sets disk in d% to be default (current drive):
0 = A, 1 = B, 2 = C, etc.
Returns number of logical drives in system in d%.

Example: CALL setdisk(0) :' Set to A:

-----------------------------------------------------------------------------
* SUB showtextfile (fi$, clr%)

*P*

An advanced routine that displays a textfile specified in fi$.
Set clr% to the foreground color to display the text file in
before calling this routine.  This is one routine that's made
to be edited and modified, so be sure to register and get the
source code version of MENULIB.

Example: CALL showtextfile("test.dat", 15)

-----------------------------------------------------------------------------
* SUB sounds (num%)

Plays a sound on the PC's speaker.
Set num% to:

1 = popup
2 = popdown
3 = klaxon
4 = siren
5 = blip
6 = 2-tone
7 = 2-tone triple
8 = 3-tone
9 = buzz
10 = chirp
11-14 = beep1-4
15 = 60hz

Example: CALL sounds(1)

-----------------------------------------------------------------------------
* FUNCTION startofline% (ln%)

Finds the position of the START OF TEXT on a specified screen line.
For example, if line 20 of the screen had the line


    This is a test

    ^
    5

on it, PRINT startofline%(20) would return 5 (the position of
the first character on the line).  If there is no text on the
specified screen line, a value of 1 will be returned.

Example: a% = startofline%(2)

-----------------------------------------------------------------------------
* SUB vscrollbar (starty%, startx%, length%)

Displays a vertical "scroll bar" on the screen starting at position
starty%/startx%m, of length% characters (vertically).  See the demo
program for an example of vscrollbar.  This routine displays the
scrollbar only - does not control scrolling or anything else.  You
will have to write the routines yourself to display a scroll indicator,
or wait for a future version of menulib <grin>.

Example: CALL vscrollbar (1, 78, 15)

-----------------------------------------------------------------------------
* SUB yesnobox (msg$, choice%)

Prints a one-line message on the screen in a box,
and waits for user to select YES, NO or CANCEL.
Returns 1 (YES), 0 (NO) or -1 (Cancel) in choice%.
Shortest string should be >20.

Example: CALL yesnobox("Are you Sure?", choice%)

-----------------------------------------------------------------------------